/**
 * 
 */
package org.dse.dao;

import java.io.Serializable;
import java.util.List;

/**
 * This interface provides methods a DAO must have at least. As a DAO, it must
 * have methods like findById, findAll. It must also have save, delete methods.
 * 
 * This interface does not give implementation. Different implementations use
 * different technologies, like Hibernate, JDO, JDBC, JPA and so on.
 * 
 * Because DAOs process more than one type, no this interface uses generic type
 * for the object and the id.
 * 
 * @author zhangchen
 * 
 */
public interface GenericDAO<T, ID extends Serializable> {

	/**
	 * Query an object using its primary key.
	 * 
	 * @param id
	 *            the primary key
	 * @param lock
	 *            the lock mode
	 * @return the object identified by the primary key
	 */
	public T findById(ID id, boolean lock);

	/**
	 * Query all objects in a specific table.
	 * 
	 * @return a list containing all objects
	 */
	public List<T> findAll();

	/**
	 * Query some objects like another object
	 * 
	 * @param exampleInstance
	 *            the object to be treated as the template
	 * @return a list containing proper objects
	 */
	public List<T> findByExample(T exampleInstance);

	/**
	 * Save an object.
	 * 
	 * @param entity
	 *            the object to be saved
	 * @return the same object
	 */
	public T makePersistent(T entity);

	/**
	 * Delete an object from the database.
	 * 
	 * @param entity
	 *            the object to be deleted
	 */
	public void makeTransient(T entity);

	/**
	 * Flush the cache in some O-R mapping technologies.
	 */
	public void flush();

	/**
	 * Clear the cache in some O-R mapping technologies.
	 */
	public void clear();
}
